<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link rel="stylesheet" type="text/css" href="style.css" />
    <title>Cygwin Package Contributor's Guide</title>
  </head>

<body>
<!--#include virtual="navbar.html" -->
<div id="main">
<!--#include virtual="top.html" -->
<h1>Cygwin Package Contributor's Guide</h1>

<p>This document is intended for people who upload packages to sourceware.org,
  to be made available through the standard Cygwin setup program.
</p>

<p>
  The <tt>cygwin-apps</tt> mailing list is the correct place to discuss any
  package creation or maintenance issues. It is not a place for end user bug
  reports - direct those to the <tt>cygwin</tt> mailing list instead.
</p>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2>See also</h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>
<ul class="compact">
  <li>More information about <a href="packaging-package-files.html">Cygwin
  package files</a>.</li>
  <li>More information about <a href="packaging-hint-files.html">.hint
  files</a>.</li>
  <li>Setup has it's
  own <a href="https://sourceware.org/cygwin-apps/setup.html">homepage</a>. If
  you are interested in adding features to setup, you should consult the setup
  homepage.
  </li>
  <li>
  If you are interested in creating a local mirror, with or without custom
  Cygwin packages, see
  the <a href="package-server.html">package
  server</a> page.
  </li>
</ul>
<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2>Contents</h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>
<ul class="compact">
  <li><a href="#making_srcpackage">Making a package with cygport</a></li>
  <li><a href="#submitting">Submitting a package</a></li>
  <li><a href="#acceptance">Uploading an accepted package</a></li>
  <li><a href="#updating">Updating a package</a></li>
</ul>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2><a id="making_srcpackage">Making a package with cygport</a></h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<p>While older, hand-made packages exist, the only accepted way to make a new
Cygwin package is using the cygport tool, which automatically handles most
packaging requirements and issues for you.  It is also strongly recommended to
convert existing packages to cygport when updating them; ask on
the <tt>cygwin-apps</tt> list if you need help converting an existing package to
use cygport.</p>

<p>The <tt>cygport</tt> framework improves
on <a href="setup-packaging-historical.html">previous Cygwin build scripts</a>, and
borrows concepts from the Gentoo portage system.</p>

<p>Suppose that the upstream's <tt>boffo-1.0.tar.xz</tt> source tar file, that you
downloaded from the boffo homepage, unpacks into <tt>boffo-1.0/</tt>.</p>

<p>Further, suppose you've got boffo ported to Cygwin. It took some work, but
you've got a patch file, which we will name <tt>boffo-1.0-fix-whatever.patch</tt>, and
with that applied <tt>boffo</tt> builds and runs.</p>

<p>All that remains is to write a <tt>boffo.cygport</tt> file which
will describe how to unpack, configure, build and package:</p>

<pre class="sample-preformat">
# package name
NAME="boffo"
VERSION=1.0
RELEASE=1

# .hint generation
CATEGORY="Games"
SUMMARY="A whackamole simulation in ASCII art"
DESCRIPTION="A whackamole simulation in ASCII art.
Intended for use on VT100 terminals at BAUD rates 1200 and
above.  Uses arrow keys for positioning over moles.  Space
bar whacks the mole.
No actual moles will be harmed during execution of this game."

# source and patch files
SRC_URI="http://boffo.org/downloads/boffo-${VERSION}.tar.xz"
PATCH_URI="boffo-1.0-fix-whatever.patch"

# use the standard src_compile, src_install and src_test
</pre>

<p>The source and binary packages can then be built and a .hint generated by running <tt>cygport boffo.cygport all</tt>.</p>

<p>For more information on using <tt>cygport</tt> consult the
<a href="https://cygwinports.github.io/cygport/cygport.1.html">man page</a>,
<a href="https://github.com/cygwinports/cygport/blob/master/README">README</a>,
<a href="https://cygwinports.github.io/cygport/toc_index.html">reference manual</a>
and sample .cygport files.</p>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2><a id="submitting">Submitting a new package</a></h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<p>So you've got a package you want to submit. Follow the following checklist before emailing the <tt>cygwin-apps</tt> mailing list, and you'll almost certainly save time.</p>
<ul class="compact">
  <li><i>Do you have the time to maintain the package?</i><br />
   Packages without active maintainers are pulled from the distribution. Generally speaking the time commitment is relatively low, simply subscribe to the <tt>cygwin</tt> mailing list. We'd prefer if you read the non-digest mode since prompt response to packaging issues is a plus. When a <i>bug</i> in your package is reported in the cygwin mailing list, address the bug (if it's a Cygwin-only bug) or pass back to the upstream. When a solution exists, create and upload an updated package with the fix in it. Note that you are not expected to be a helpdesk for the package - the users should be pointed to the upstream's lists if you've determined that the bug is not a Cygwin-related bug.</li>
  <li>
    Propose on the <tt>cygwin-apps</tt> mailing list that you are interested in becoming a package maintainer for package "foo" using a subject like "[<a href="acronyms/#ITP">ITP</a>] foo 0.10".<br />
    Some packages cannot be distributed via Cygwin's setup due to upstream licence limitations. Other packages may not be appropriate for Cygwin. This step will save time if, for some reason, we cannot accept the package.<br />
    Submission rules:<br />
    <ul class="compact">
      <li><b>Include a complete <tt>.hint</tt> file as part of your proposal</b>. Include this file in the text of your message so that it can be commented on. Do not submit it as an attachment.</li>
      <li>If the new package is a well-known program already included in a major Linux distribution (e.g. Debian, Fedora, SuSE) please <b>include the URL</b> of the package page.  Note that "development", "test", and "unstable" packages are <b>not eligible</b> for this rule.</li>
      <li>If the package is not included in any major Linux distro it must receive <b>five positive votes</b> from other package maintainers in order to be accepted.</li>
      <li>It's helpful to mention which <a href="https://opensource.org/licenses">open source license</a> applies to the source.</li>
    </ul>
  </li>
  <li>
    In order to create a good <tt>.hint</tt> file do read and follow <a href="packaging-hint-files.html#pvr.hint">the documentation</a>.<br />
    A few things to take extra care to:<br />
    <ul class="compact">
      <li>In order to select an appropriate a correct <tt>Category</tt> you can look in the Debian package list and identify the section that your package is present in there - if it's available via Debian. If it's not, have a look and take a sensible guess. Use <a href="packaging-hint-files.html#categories">existing categories</a> if at all possible.</li>
      <li>Do not use the package name in <tt>sdesc</tt>, as it is added automatically by the setup program.</li>
      <li>Opinion on whether to mark your initial version as a <tt>Test</tt> version is currently mixed. If you have doubts about the stability of your initial offering you may decide to mark it as <tt>Test</tt>. Then, once the package has no major bug reports from users, a current package may be introduced. Otherwise, it is perfectly acceptable to forgo the <tt>Test</tt> designation in your first release.</li>
    </ul>
  </li>
  <li>
    Place the package files in a web accessible http/ftp site somewhere. If at all possible the files should have a directory structure in order to get them all with a single command.<br />
    For example, if I am proposing "foo" and "libfoo", an upload site should look like:<br />
    <ul class="compact">
      <li><tt>myserver.com/whatever/x86/foo/foo-0.20.3-1.tar.xz</tt></li>
      <li><tt>myserver.com/whatever/x86/foo/foo-0.20.3-1-src.tar.xz</tt></li>
      <li><tt>myserver.com/whatever/x86/foo/foo-0.20.3-1.hint</tt></li>
      <li><tt>myserver.com/whatever/x86/foo/libfoo/libfoo-0.20.3-1.tar.xz</tt></li>
      <li><tt>myserver.com/whatever/x86/foo/libfoo/libfoo-0.20.3-1.hint</tt></li>
    </ul>
  </li>
  <li>Announce on the <tt>cygwin-apps</tt> mailing list that you have the package ready for uploading. Provide the URLs of all package files in your mail.</li>
  <li>Each new package must in any case receive one <a href="acronyms/#GTG">GTG</a> vote from a package maintainer, meaning that an existing maintainer has downloaded the package, inspected the tar file contents, tested the applications, and rebuilt the package from the source tar file without incident. Once a successful package is produced, you become a maintainer yourself and can provide GTG reviews for others as well.</li>

</ul>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2><a id="acceptance">Uploading an accepted package</a></h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<ol>
  <li>Once you have your GTG,
      follow <a href="package-upload.html">these
      instructions</a> for submitting a ssh key and uploading your package files.</li>
  <li>Announce via the <tt>cygwin-announce</tt> mailing list that the new package is available. Use the <a href="#announcement">announce message example</a> listed later in this page as a template for your announcement.<br />
    Be sure the unsubscribe instructions are included at the end of the email, since cygwin-announce does not add any.<br />
    Once sent, your message will be reviewed by one of the cygwin-announce moderators and, once approved, will be automatically forwarded to the cygwin mailing list with an [ANNOUNCEMENT] prepended to the subject.</li>
  <li>Feel free to delete your local copy once the files have been uploaded to sourceware.org.</li>
</ol>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2><a id="updating">Updating a package</a></h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<p>So you've got an updated package you want to submit. You should
  already have upload privileges, and should be able to do the entire
  process yourself, by
  following <a href="package-upload.html">these
  instructions</a>.  If you encounter any problems, email
  the <tt>cygwin-apps</tt> mailing list.</p>
<ol>
  <li>There is no need to increase the release number if the package has not been officially released.  So, if you are releasing a -1 release of a package keep using -1 for any refinements <em>until</em> the package has been uploaded.</li>
  <li>Thereafter, you <em>must</em> increase the version or release number when
    uploading an updated version of the package.</li>
  <li>After doing a upload, announce via the <tt>cygwin-announce</tt> mailing list that the new package is available. Use the <a href="#announcement">announce message example</a> listed later in this page as a template for your announcement..<br />
   Once sent, your message will be reviewed by one of the cygwin-announce moderators and, once approved, will be automatically forwarded to the cygwin mailing list with an [ANNOUNCEMENT] prepended to the subject.</li>
</ol>
<p>NOTE: On any major version upgrade, you may want to mark the release as <tt>Test</tt>.</p>
<h3><a id="announcement">Example announcement</a></h3>
<br/>
<table class="sample-email">
  <tr>
    <td width="20%"><i>Subject:</i></td>
    <td><tt><b>New package: foo-0.30.2-1</b></tt><br />
     <i>or</i><br />
     <tt><b>Updated: foo-0.30.2-1</b></tt> </td>
  </tr>
  <tr>
    <td colspan="2"><tt>Version 0.30.2-1 of "foo" has been uploaded.<br />
    <br />
     (a couple of lines about what "foo" is)<br />
     (short changelog of important features or fixes; big emphasis for security fixes)<br />
    <br />
     &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*** CYGWIN-ANNOUNCE UNSUBSCRIBE INFO ***<br />
    <br />
     If you want to unsubscribe from the cygwin-announce mailing list, look at the "List-Unsubscribe: " tag in the email header of this message. Send email to the address specified there. It will be in the format:<br />
    <br />
     cygwin-announce-unsubscribe-you=yourdomain.com &lt;at&gt; cygwin&#46;com<br />
    <br />
     If you need more information on unsubscribing, start reading here:<br />
    <br />
     https://sourceware.org/lists.html#unsubscribe-simple<br />
    <br />
     Please read *all* of the information on unsubscribing that is available starting at this URL.</tt> </td>
  </tr>
</table>

</div>
</body>
</html>
